PATH
PATH
MacOS X Server Release Notes Copyright © 1999 by Apple Computer, Inc. All Rights Reserved.
The Application Framework (sometimes referred to as the AppKit) is one of the core Yellow Box frameworks. It provides functionality and associated APIs for applications, including objects for graphical user interfaces (GUIs), event-handling mechanisms, application services , and drawing and image composition facilities. It is also a cross-platform framework; thus all features described below are available both on MacOS X Server and Yellow Box for Windows unless otherwise noted. In addition, it is possible to access virtually all of the classes and protocols in the Application framework using Java.
The notes below are split into the following sections:
The Application Kit includes the following new features and changes since Developer Release 2.
Mac OS X Server 1.0 introduces support for scriptable Yellow applications. The support is still considered beta-quality, and is provided for developers to get started making their applications scriptable. See the scripting release note and the documentation for more details. TextEdit and both the Java and Objective-C version of Sketch support scripting and can be used as examples of how to implement scripting in a Yellow application.
Yellow frameworks now have support for ActiveX when running on Windows. See the ActiveX release note for more details. The WebBrowser example shows how to use ActiveX embedding.
Sound
A new class, NSSound, has been added to the AppKit. This class offers simple cross-platform sound-playing capabilities to applications. Editing and recording of sounds is not supported, nor is manipulation of sound parameters (volume, left/right gain, etc.). The sound formats that are understood are the a-law, u-law, 8- and 16-bit signed and unsigned linear encodings of the Microsoft WAV and NeXT/Sun SND (AU) formats. These formats are understood on either platform.
The NSButton and NSButtonCell classes have setSound: methods that can be used to associate a sound with a button.
MovieView
The AppKit now includes an NSMovieView that can be used to play QuickTime movies. It contains sufficient functionality to create an application such as MoviePlayer but does not give full access to all of the QuickTime APIs for content creation. The movie is always resized to fill the whole view and the view can be embedded in another view with appropriate clipping. Note that loading a movie view takes a few seconds when first starting to load the QuickTime libraries. There is an outstanding bug which causes the application to crash if the view is resized to zero width or height.
Binary compatibility on Windows
Due to a bug fix in the Objective-C runtime, binaries from DR2 and previously will not run on Yellow Box for Windows 1.0. These applications should be fully recompiled.
ColorSync support in NSBitmapImageRep
The property dictionary in NSBitmapImageRep has a key declared in NSBitmapImageRep.h as NSImageColorSyncProfileData. The value for this key is an ICC profile.
In 1.0, ColorSync correction of images during display is supported on all architectures. Prior to 1.0 it was only supported on ppc.
Also, when the bitmap image rep is turned into a TIFF representation, the ICC profile is written into the tiff representation. Prior to 1.0, profiles embedded in tiff representations were only supported during reading.
If an NSImage replaces an NSBitmapImageRep by an NSCachedImageRep, the color sync profile is consumed and no longer part of the property dictionary. The values of the pixels in the cached image rep are the ColorSync corrected ones.
Apple Menu items
You may want installation of your application to result in additional items appearing in each user's Apple Menu. To do this, you need to install a bundle in the library search path. For example, if your application was being installed in /Local/Applications, you would add a bundle to /Local/Library/AppleMenu.
The bundle must have the extension .appleMenuItems. Inside the bundle there should be a file AppleMenuItems.plist. If the bundle is localized, there would be a file, AppleMenuItems.strings, in each .lproj for which it is localized. Only the user-visible title of the item needs to be localized.
The format for the plist is not explicitly documented. There is however a substantial example inside the AppKit at /System/Library/Frameworks/AppKit.framework/Resources/English.lproj/AppleMenuItems.plist and /System/Library/Frameworks/AppKit.framework/Resources/English.lproj/AppleMenuItems.strings.
Currently all Apple Menu items found via these search paths are collected and localized once per login. The items become the backdrop against which users make their individual customizations. A user with no customizations sees all the items.
In order to give attachments more information about the environment they are being asked to draw in, the NSTextAttachmentCell protocol has been extended. The following methods have been added to the protocol:
- (void)drawWithFrame:(NSRect)cellFrame
inView:(NSView *)controlView characterIndex:(unsigned)charIndex;- (BOOL)trackMouse:(NSEvent *)theEvent
inRect:(NSRect)cellFrame
ofView:(NSView *)controlView
atCharacterIndex:(unsigned)charIndex
untilMouseUp:(BOOL)flag;- (NSRect)cellFrameForTextContainer:(NSTextContainer *)textContainer
proposedLineFragment:(NSRect)lineFrag
glyphPosition:(NSPoint)position
characterIndex:(unsigned)charIndex;Effects on existing conformers to the NSTextAttachmentCell Protocol
Existing applications and object files are binary-compatible and do not require recompilation. However, under certain circumstances, you will need to make source changes to recompile existing conformers to the NSTextAttachmentCell protocol. Subclasses of the class NSTextAttachmentCell do not need to be changed; that class implements the new methods by calling the older -cellSize, -cellBaselineOffset, -drawWithFrame:inView:, and -trackMouse:inRect:ofView:untilMouseUp: methods. However, other classes which conform to this protocol will have to be modified in order to recompile. The simplest change is to simply remove the protocol from the class (i.e. remove "<NSTextAttachmentCell>" from the @interface line for your class); this will produce warnings when you recompile, but the resulting application or framework will work as expected. A more complete fix is to implement the new methods to call the old ones, exactly as the class NSTextAttachmentCell does. The most straightforward implementation appears below:
- (NSRect)cellFrameForTextContainer:(NSTextContainer *)textContainer
proposedLineFragment:(NSRect)lineFrag
glyphPosition:(NSPoint)position
characterIndex:(unsigned)charIndex {
NSRect result;
result.origin = [self cellBaselineOffset];
result.size = [self cellSize];
return result;
}- (BOOL)trackMouse:(NSEvent *)theEvent
inRect:(NSRect)cellFrame
ofView:(NSView *)controlView
atCharacterIndex:(unsigned)charIndex
untilMouseUp:(BOOL)flag {
return [self trackMouse:theEvent inRect:cellFrame ofView:controlView untilMouseUp:flag];
}- (void)drawWithFrame:(NSRect)cellFrame
inView:(NSView *)controlView
characterIndex:(unsigned)charIndex {
[self drawWithFrame:cellFrame inView:controlView];
}New conformers to the protocol
When writing a new class that conforms to the NSTextAttachmentCell protocol, first decide whether you need the added information in the new, richer methods. If not, simply implement these methods to call the older, simpler methods, as shown above. If you want to take advantage of the richer methods, however, you should implement the richer methods, then override the older methods to call the richer ones, passing dummy arguments. For instance, if you want to use the text container and line fragment information when sizing your attachment, implement -cellFrameForTextContainer:proposedLineFragment:glyphPosition:characterIndex: to properly calculate the size and location of your cell. Then implement the older methods -cellSize and -cellBaselineOffset to call this method, passing dummy arguments (your -cellFrameForTextContainer:.... method should be tolerant of this case, and fall back to some simple sizing algorithm). This gives you:
- (NSRect)cellFrameForTextContainer:(NSTextContainer *)textContainer
proposedLineFragment:(NSRect)lineFrag
glyphPosition:(NSPoint)position
characterIndex:(unsigned)charIndex {
NSRect result;
if (!textContainer) {
// Do some simple size calculation here
...
} else {
// Do your full size calculation here
...
}
return result;
}- (NSPoint)cellBaselineOffset {
return [self cellFrameForTextContainer:nil proposedLineFragment:NSZeroRect
glyphPosition:NSZeroPoint characterIndex:NSNotFound].origin;
}- (NSSize)cellSize {
return [self cellFrameForTextContainer:nil proposedLineFragment:NSZeroRect
glyphPosition:NSZeroPoint characterIndex:NSNotFound].size;
}The AppKit text system will never call the older methods; however, other classes that check for the protocol might, so you should make sure to implement the complete set.
In addition to the above changes, the following methods were added to NSLayoutManager to allow this to work:
- (void)setAttachmentSize:(NSSize)attachmentSize forGlyphRange:(NSRange)glyphRange;
- (NSSize)attachmentSizeForGlyphAtIndex:(unsigned)glyphIndex;
- (void)showAttachmentCell:(NSCell *)cell inRect:(NSRect)rect
characterIndex:(unsigned)attachmentIndex;The last one deprecates the following method, which will continue to work in 1.0:
- (void)showAttachmentCell:(NSCell *)cell atPoint:(NSPoint)point;
Using NSURL to load resources
NSURL's API has been enriched to make it possible to load resources from the network and the web, either in the foreground or the background. To load an URL in the foreground, call resourceDataUsingCache:passing YES or NO, depending on whether you wish to use the cache. If you use the cache, NSURL will see if it or an equivalent URL has already been loaded and saved in the cache. If so, it will return the cached resource data. If not, it will start a fresh load of the URL, returning only after the URL's data has been fully loaded. If you do not use the cache, a fresh load will be started regardless. To load an URL in the background, call loadResourceDataNotifyingClient:usingCache:. This method will start the background load, then return immediately. As the resource is loaded, the client will receive messages from the NSURLClient informal protocol (if the client implements them):
@interface NSObject(NSURLClient)
- (void)URL:(NSURL *)sender resourceDataDidBecomeAvailable:(NSData *)newBytes;
- (void)URLResourceDidFinishLoading:(NSURL *)sender;
- (void)URLResourceDidCancelLoading:(NSURL *)sender;
- (void)URL:(NSURL *)sender resourceDidFailLoadingWithReason:(NSString *)reason;
@end
The client will receive some number (possibly zero) of URL:resourceDataDidBecomeAvailable: messages, followed by exactly one of URLResourceDidFinishLoading:, URLResourceDidCancelLoading:, or URL:resourceDidFailLoadingWithReason:. The client need only implement those methods that it is interested in receiving.
NSURLHandle and its subclasses
An NSURL loads its resource by using a helper object of the class NSURLHandle. NSURLHandle itself is an abstract superclass, which defines the way by which URLs communicate with their handles. Subclasses of NSURLHandle register for a particular scheme (http, ftp, file, etc.), then implement the actual loading mechanism for that scheme. Currently, Foundation only provides subclasses for the file and http schemes.
Each NSURLHandle subclass also defines a number of properties for the scheme it services. For instance, the permissions, type and size of a file are all properties of file URLs (URLs of the form file:///some-path). You can ask an URL for one of its properties by sending it the propertyForKey: message, passing the key for the property you want. HTTP URLs provide their HTTP header data as properties; use the name of the header field you are interested in as the key. File URLs provide their file attributes as properties; use the file attribute strings defined in NSFileManager.h.
Although there are a number of convenience methods available on NSURL for loading resources and querying properties, some applications will find that the functionality exported by NSURL is not sufficient for its needs. For more extensive control, you should get the NSURLHandle from the NSURL, then message the handle directly. You can do that by sending the NSURL the URLHandleUsingCache: message. For further information about NSURLHandle, look at the header file, NSURLHandle.h.
Writing your own NSURLHandle subclass
One thing a framework of application may want to do is add the ability to handle a new scheme. For instance, you may want to add ftp handling, or perhaps your own custom scheme. You can do this by subclassing NSURLHandle. Your subclass will need to override and implement the following methods:
+ (BOOL)canInitWithURL:(NSURL *)anURL;
+ (NSURLHandle *)cachedHandleForURL:(NSURL *)anURL;
- initWithURL:(NSURL *)anURL cached:(BOOL)willCache;
- (id)propertyForKey:(NSString *)propertyKey;
- (id)propertyForKeyIfAvailable:(NSString *)propertyKey;
- (BOOL)writeProperty:(id)propertyValue forKey:(NSString *)propertyKey;
- (BOOL)writeData:(NSData *)data;
- (NSData *)loadInForeground;
- (void)beginLoadInBackground;
- (void)endLoadInBackground;Your subclass should implement canInitWithURL: to return YES if it can service the given URL, and NO otherwise. cachedHandleForURL: should look in the cache (maintained by your subclass) for an existing handle that services an URL identical to the one passed. If so, the cached handle should be returned. If not, a new handle should be created for the URL, stored in the cache, then returned. initWithURL:cached: is the designated initializer for NSURLHandle; the second argument specifies whether the handle will be placed in the cache.
propertyForKey: should fetch the value for any properties that your subclass defines, and return nil for any unrecognized properties. propertyForKeyIfAvailable: should return nil unless the property is already readily available.
If your subclass allows writing out properties or data, you should implement writeProperty:forKey: and writeData: to attempt to write out their arguments, then return YES if the write succeeded, and NO otherwise. Otherwise, you should implement them to simply return NO.
The last three methods, loadInForeground, beginLoadInBackground, and endLoadInBackground do the meaty work of your subclass. They are called from resourceData, loadInBackground, and cancelLoadInBackground respectively, after checking the status of the handle. (For instance, resourceData will not call loadInForeground if the handle has already been loaded; it will simply return the existing data.) loadInForeground should synchronously fetch and return the URL's resource data. beginLoadInBackground should start a background load of the data, then return. As the background load progresses, your subclass should message itself with didLoadBytes:loadComplete:, passing the bytes received, and whether the load has finished. If the load fails at any point, your subclass should call backgroundLoadDidFailWithReason:, passing a human-readable string giving the reason for the failure. NSURLHandle implements these methods to inform its clients (including the URL itself) of the new status. Finally, your subclass should override cancelLoadInBackground to stop a background load in progress. Once a handle has received a cancelLoadInBackground message, it must not send any further didLoadBytes:loadComplete: or backgroundLoadDidFailWithReason: messages.
Now all that remains is to inform NSURLHandle of your new subclass; you do this by sending the NSURLHandle class the registerURLHandleClass: message, passing your subclass as the argument. Once this message has been sent, as NSURLHandle is asked to create handles for a given URL, it will in turn ask your subclass if it wants to handle the URL. If your subclass responds YES, NSURLHandle will instantiate your subclass for the URL.
Using NSUndoManager from Java
Because the invocation-based undo registration mechanism is unavailable in Java, the Java API of NSUndoManager has been enriched. The following method has been added to NSUndoManager:
public native void registerUndoWithTargetAndArguments(
java.lang.Object target,
com.apple.yellow.foundation.NSSelector selector,
java.lang.Object arguments[]);This allows the caller to put an arbitrary method invocation on the undo stack. The first argument is the intended receiver for the method, the second argument specifies the method, and the third argument is the array of arguments to be passed.
Note that the arguments array is an array of Objects. When your method takes scalar types, you should use the equivalent Java wrapper classes in the arguments array. For instance a method which takes an int should build a java.lang.Integer instance that contains that int to put into the arguments array. The undo manager will resolve all this by the time it needs to build the invocation to send. See the Java version of the Sketch application's source code for an example of the use of this new method.
There is a known bug which prevents float arguments (registered as java.lang.Float objects) from being properly registered; Methods which take floats will not be able to be undone properly at this time. The argument will always be zero by the time your method is invoked from the undo manager. Sketch has this problem with the setStrokeLineWidth() method in the Graphics class. You can work around this by having your method take a java.lang.Float instead. This bug should be addressed in an upcoming release.
Using Undo with the Text System
A design flaw has been discovered when using undo with the AppKit text system. If you have a text view and have enabled undo with it by calling [myTextView setAllowsUndo:YES], the undo stack managed by the text view will become corrupted if the text storage is manipulated directly. A handful of methods on NSTextView (the methods inherited from NSText of the form -replaceCharactersInRange:....) will also corrupt the undo stack. Once corrupted, calls to undo and redo will have unexpected results, possibly crashing the application. To avoid this, we recommend that you either manipulate the text only through the safe NSTextView methods, manage the undo stack yourself, or disable undo. This bug will be resolved in a forthcoming release.
TableView
Notes on the autosave columns feature:
Column identifiers used with NSTableView's "autosaveTableColumns" feature must conform to the NSCoding protocol. NSTableView will raise an exception if the user attempts to perform the autosave (into User Defaults) on a table column identifier that is not an archivable object. In DR2, the view would allow one to attempt this, and the program would crash mysteriously during User Defaults writing.
The autosave feature is only actually enabled when there is an autosave name set. code should call setAutosaveName: before calling setAutosaveTableColumns:YES. In previous releases, this would autosave any nameless tableview with the same key, "NSTableView Columns *nil*".
The correct way to use this feature for NSTableView instances in NIB files is to set the name and enable it after the NIB file is loaded and before display occurs. The "awakeFromNib" method in a controller class is a good place to do this.
Because of this autosave feature, notifications of column width changing are suspended while a NSTableView is tiling itself or otherwise laying itself out by a user column-resize operation. The columns are saved upon completion of the layout operation. Were the notifications not suspended, the setWidth: calls during layout would cause notifications to be sent and column settings to be saved. This change prevents autosave from happening during layout and resizing operations.
Note: Developers may find that programs which utilized the autosave feature in DR2 can crash or raise an exception when trying to read old defaults under the new regime. (The exception would typically occur in methods called through the private method _readPersistentTableColumns; and the NSLog message will state that NSInlineUnicodeString does not respond to the bytes method.) The crash can be remedied by first removing the old autosave defaults for that application. (Use "defaults delete TheApp TheKey", or when in doubt, "defaults delete TheApp" to remove all of the defaults for the offending application.
Columns are saved by column identifier. In the DR2 release, the column identifier was expected to always be an NSString, though it is properly an "id" type. In this release, the column identifier can be any object that responds to the NSCoding protocol (though typically an NSNumber of an NSString).
Notes on cell editing and data reloading:
When the reloadData method is called, any cell that is in the midst of being edited will lose the editing changes currently in progress. (I.e., a cell that has the blinking cursor at the time of the reload will lose whatever has changed.) This can be remedied by explicitly ending the editing session before the reload, which will preserve the data in the cell. Before sending reloadData to the Table View, send endEditingFor: to the window in which it lives. For example:
[[myTabView window] endEditingFor:self];
[myTabView reloadData];
OutlineView
The delegate method outlineView:willDisplayOutlineCell:forTableColumn:item: was never being sent. This has been fixed so that it is called (if the delegate responds to it) just before the cell is drawn.
The method removeTableColumn: should not be used for the "outline table column", and if an attempt is made to do that (which would result in an inconsistent state), the method will log an error and no change will take place. Use the setOutlineTableColumn: method to properly replace the outline table column if necessary. First, add a new column if you need to, then use setOutlineTableColumn: to switch to the new table column, then remove the old column if desired.
Notes on Support for the "Euro" Currency Sign
Most of the fonts shipped with this release have not been modified to include the new "Euro" currency sign of the European Monetary Union. The Charcoal font, however, has been modified to include this glyph in the encoding position formerly reserved for the International Currency Sign, a seldom-used character. It is expected that in the future if other fonts are modified, they would likewise include the Euro sign at this position. The character encoding for the Euro sign in the Unicode standard is U+20AC, as documented in Unicode Technical Report #8. (The International Currency Sign is encoded at U+00A4.)
To facilitate use of the Euro sign without system modifications, if new fonts containing it are added by users or other vendors, both the character for the Euro sign and for the International Currency Sign are rendered with the glyph encoded at 0x00A8 in the "NextStep" font encoding.
In other words: in the Charcoal font, the glyph for the International Currency Sign is unavailable, having been replaced by the glyph for the Euro sign. In the other fonts, the glyph for the Euro sign is unavailable. However, all NextStep-encoded fonts respond as if the glyph for the Euro sign were encoded at 0x00A8.
To display the proper glyph for the Euro sign in plain text, you may use the Charcoal font. To display the proper glyph in RTF or other fancier formatted documents, you may enter the character U+20AC, select it, and change the font of that one character to Charcoal.
Notes on Keyboard Support for the "Euro" Currency Sign
Most of the keyboard layouts shipped with Mac OS X Server now have the Euro sign attached to the Alt-Shift-4 key combination. If the keyboard layout you have chosen is not configured this way, or if you wish to change the key combination for generating the Euro, you can use Keyboard.app which can be found in /System/Demos.
Because keymaps currently do not support the assignment of actual Unicode characters, thetechnique for assigning the Euro sign to a key is not obvious. To assign the Euro to a key, you should use the 0xa0 encoding slot of the Symbol character set. This encoding slot is unused in the standard Symbol encoding.
To assign this to a key, open your keyboard mapping file in Keyboard.app, select the key you want on the picture of a keyboard and make sure that the checkboxes for any modifiers you want are checked. For example, to assign it to Alt-Shift-4, select the four key and check the Shift and Alternate checkboxes. Then, using the Character Code Palette (available from the Tools menu), select the Symbol encoding from the popup at the bottom of the window and drag the chip for 0xa0 onto the keyboard and drop it on the key that you want to assign. Slot 0xa0 is the 1st column of the 11th row of the Character Code Palette. When you have assigned the Euro sign to the key you want, save the keyboard mapping into your ~/Library/Keyboards directory (creating the Keyboards directory if necessary), and use Preferences.app to select your new keyboard mapping.
Typesetter
NSTypesetter has been made a public class in this release. The class NSTypesetter itself is abstract. The one concrete subclass is NSSimpleHorizontalTypesetter, which is the class used as the default throughout the system. Some instance variables of the concrete class are accessible for use by subclassers.
The following NSLayoutManager methods have been exposed to support use of custom NSTypesetter subclasses:
- (NSTypesetter *)typesetter;
- (void)setTypesetter:(NSTypesetter *)typesetter;
- (unsigned)getGlyphsInRange:(NSRange)glyphsRange
glyphs:(NSGlyph *)glyphBuffer
characterIndexes:(unsigned *)charIndexBuffer
glyphInscriptions:(NSGlyphInscription *)inscribeBuffer
elasticBits:(BOOL *)elasticBuffer
Browser
Some delegate methods of the NSBrowser (notably browser:columnOfTitle:) depend on the option-settings and state of the browser instance at the time the setDelegate: method is called, but the documentation is not clear on this point. It is best to take care of all option settings of the browser instance (such as setTitled: and setTakesTitlesFromPreviousColumn:) before setting the delegate via setDelegate:.
Window
NSWindow now has -isZoomed API to let you ask whether a window is currently zoomed. The answer will be YES if hitting the zoom box or calling the zoom: method would cause the window to restore the last user state. It will be NO if hitting the zoom box would cause the window to zoom.
DocumentController
The Java signatures for the following methods have changed to be more specific. This change will require a recompile of Java applications that use the document architecture.
public static native NSDocumentController sharedDocumentController();
public native NSDocument makeUntitledDocumentOfType(java.lang.String);
public native NSDocument makeDocumentWithContentsOfFile(java.lang.String, java.lang.String);
public native NSDocument makeDocumentWithContentsOfURL(java.net.URL, java.lang.String);
public native NSDocument openUntitledDocumentOfType(java.lang.String, boolean);
public native NSDocument openDocumentWithContentsOfFile(java.lang.String, boolean);
public native NSDocument openDocumentWithContentsOfURL(java.net.URL, boolean);
public native NSDocument currentDocument();
public native NSDocument documentForWindow(com.apple.yellow.application.NSWindow);
public native NSDocument documentForFileName(java.lang.String);These methods all used to return java.lang.Object in DR2.
WindowController
The Java signatures for the following NSWindowController method has changed to be more specific. This change will require a recompile of Java applications that use the document architecture.
public native NSDocument document();This method used to return java.lang.Object in DR2.
Application
activateIgnoringOtherApps: will now unhide and activate a hidden application if flag is YES. In DR2 and previous releases, this method had no effect on a hidden application.
NXOpen, NXOpenTemp, and NXPrint are no longer recognized as command line options. Any use of these keywords should be replaced by NSOpen, NSOpenTemp, and NSPrint, respectively.
Threading
It is now possible to create a window on a secondary thread.
It is now possible to call [NSApplication postEvent:atStart:] from a secondary thread. This will result in delivery of the event to the event queue on the main thread.
In DR2, multi-threaded applications could hit a race condition where a font defined on one thread was not accessible on another. This has been fixed for drawing fonts. The fix does not apply to printing fonts, but this should not be a problem as it is not expected that an application will be printing from two threads at once.
For additional release notes on threading support please see ThreadSupport.html.
Using NSFileHandle with sockets on Windows
Because read() and write() do not work on sockets on Windows, a file handle created with [[NSFileHandle alloc] initWithNativeHandle:(HANDLE)someSocketHandle] was not usable.
If read() and write() fail, the file handle implementation now tries recv() and send(), respectively, and a file handle created this way is now usable.
You may find it particularly convenient to go through the NSFileHandle API in cases where you do not know whether a handle is a socket or a handle to a regular file system file. For example, a child process whose parent set it up to read or write from a socket using stdin and stdout can successfully read from stdin and stdout using the file handle API, whereas stdio library calls such as getchar() and putchar() will fail.
Dragging on Windows
Due to an incorrect match between messages sent by the OLE drag manager and the NSDraggingDestination informal protocol, draggingEntered: was sent repeatedly and draggingUpdated: was not sent. Developers who have worked around these longstanding problems should remove their workarounds as of this release.
Continuous Completion in NSComboBox and NSComboBoxCell
A new method setCompletes: has been introduced. If completes is YES, after each change to the text of a combo box cell, completedString: is called. If the string returned by completedString: is longer than the existing text, the text is replaced, and the additional material is selected. If the user is deleting text or the selection (or insertion point) is not at the end of the text, completion is not attempted.
An implementation of completedString: is provided. If the combo box (or combo box cell) uses a data source, and the data source responds to comboBox:completedString: (or comboBoxCell:completedString: in the combo box cell case) the return value of this method is used. Otherwise, this implementation just goes linearly through the items until it finds an item which is suitable as the completed string. Subclassers of completedString: do not need to call super. It is ok to return nil (in which case no completion occurs). completedString: is generally not called directly.
ButtonCell
The constants NSMomentaryPushButton and NSMomentaryLight where reversed. If you called [NSButtonCell setButtonType:] with these constants, they would do the wrong thing. For compatability, these constant names have been kept but new ones with the correct naming have been introduced: NSMomentaryLightButton and NSMomentaryPushInButton.
StatusItem
The limit on the width of status bar items has been increased (to 10,000, basically unlimited).
MenuItem
The Windows implementation of NSMenuItem now supports black and white images for use as marks to indicate on, off, or mixed states. If custom images are not set, then the checkmark is used for the on state, the dash is used for the mixed state, and no image is used for the off state. The image will be centered in the bounds of the menu item icon.
ToolTips
In DR2 and previously, tool tips did not work in modal windows. They now do.
Standard About Panel
The following two methods have been added to NSApplication to allow putting up a standard About panel. The first one allows you to specify the various fields. Default values (as described below) are used for fields that are not specified. The second method, intended for target/action usage, simply uses all default values:
- (void)orderFrontStandardAboutPanelWithOptions:(NSDictionary *)optionsDictionary;
- (void)orderFrontStandardAboutPanel:(id)sender;The following are keys that can occur in optionsDictionary:
"Credits": NSAttributedString displayed in the info area of the panel. If not specified, contents obtained from "Credits.rtf" in [NSBundle mainBundle]; if not available, blank.
"ApplicationName": NSString displayed in place of the default app name. If not specified, uses the value of NSHumanReadableShortName in the localized version of Info.plist. If that's not available, uses [[NSProcessInfo processInfo] processName].
"ApplicationIcon": NSImage displayed in place of NSApplicationIcon. If not specified, use [NSImage imageNamed:@"NSApplicationIcon"]; if not available, generic icon.
"Version": NSString containing the build version number of the application ("58.4"); displayed as "(v58.4)". If not specified, obtain from the NSBuildVersion key in infoDictionary; if not specified, leave blank (the "(v)" is not displayed).
"Copyright": NSString containing the copyright string. If not specified, obtain from the value of NSHumanReadableCopyright in the localized version InfoDictionary; if not available, leave blank.
"ApplicationVersion": NSString displayed as the application version ("MacOS X Server", "WebObjects 3.5", "ClarisWorks 5", ...). If not specified, obtain from the NSAppVersion key in Info.plist. If not available, leave blank; then the build version, if provided, is displayed as "Version 58.4".
Attributed Strings in FoundationJava
Note that although the NSAttributedString constructors from AppKit are listed in FoundationJava in the Yellow/Java APIs, these are still implemented in the AppKit and require AppKit to be linked in to be usable.
Text
The text object now supports more sophisticated underlining; you can underline by words, and by strikethrough. You can "or" together NSUnderlineByWordMask and NSUnderlineStrikethroughMask with the base underline style (NSNoUnderlineStyle or NSSingleUnderlineStyle) to get the desired effect.
In DR2 and previously, hyphenation could (especially with high hyphenation factors, above 0.8) cause display glitches (overwritten lines, for instance) in some rare circumstances. This is now fixed.
A leak in the text system that caused the text view and related objects to leak when undo was enabled has been fixed.
SplitView
The following delegate method:
- (void)splitView:(NSSplitView *)sender
constrainMinCoordinate:(float *)min
maxCoordinate:(float *)max
ofSubviewAt:(int)offset;was deprecated in favor of:
- (float)splitView:(NSSplitView *)sender
constrainMinCoordinate:(float)proposedCoord
ofSubviewAt:(int)offset;- (float)splitView:(NSSplitView *)sender
constrainMaxCoordinate:(float)proposedCoord
ofSubviewAt:(int)offset;In 1.0, the old one will be called if it's still implemented.
View
New method lockFocusIfCanDraw has been introduced. Any thread drawing directly (eg. outside of the standard display mechanism) should use this method to check drawing validity before it starts drawing.
FileWrapper
The string encoding for a serialized directory wrapper is changed from NSNEXTSTEPStringEncoding to NSUTF8StringEncoding. This means non-ASCII characters in serialized RTFD data lose backward compatibility.
The alpha versions of the Java APIs to the Yellow Box have been removed. They were provided in DR2 for compatibility only.
The Application Kit includes these new classes, features, and changes since the first Developer Release. Many of the new features have been documented, so please refer to the documentation for more detail.
The Java APIs to the Yellow Box, which were distributed in their alpha form in the first Developer Release, have undergone some changes and are now considerably more robust and finalized. Please see the Java APIs release note for details.
The new NSDocument, NSDocumentController, and NSWindowController classes ease the task of creating document-based applications. These classes encompass a lot of the behavior that applications commonly implement to deal with documents. Document-based applications that use these classes will be better suited to take automatic advantage of new features added to the Yellow Box.
Instances of NSDocument represent documents. NSDocument is abstract; you subclass it to add storage for the document and behaviors such as reading and writing. An NSDocument appears in the responder chain right after its window's delegate, and the NSDocument is set up to be the first-responder target for various actions such as save, revert, and print. In addition, NSDocument manages its window's edited status and implements much of the behavior required for undo and redo operations.
Each application has one instance of NSDocumentController, which manages the list of documents and implements application-wide behavior.
NSWindowController provides basic nib-file and window management. For simple situations (one document, one window), you will usually have one instance of NSWindowController per document. An NSWindowController can also be used to manage windows in non-document-based applications. Subclassing is optional.
A new project type, "Document Based Application," facilitates the initial setup required to create an application based on these new classes.
To better support the new document object and the Finder (in upcoming releases), some changes were made in the contents of the Info.plist and CustomInfo.plist files found in application wrappers and bundles. See the release note on the Information Property List Format for details.
Enterprise Object Framework's EOUndoManager has been modified and made a new Foundation class, NSUndoManager. This class makes it easier for applications to support undo and redo operations. Clients register callbacks that the undo manager invokes when users request an undo or redo operation. NSUndoManager supports grouping and multiple levels of undo.
NSResponder now provides a method called undoManager;
clients should use this method to get access to an NSUndoManager.
The default behavior in NSResponder is to call the next
responder; this usually ends up in NSWindow, which is in the
responder chain. The default behavior of NSWindow is a bit more
complicated; if the window has a window controller with a
document, NSWindow implements this method by first looking to see
if its document has an undo manager and returning it if that is
so. Otherwise, NSWindow invokes the new delegate method undoManagerForWindow:
If the delegate doesn't implement this method NSWindow creates
and returns its own NSUndoManager.
The text system now also supports undo and redo operations.
Although DR2 contains no scripting features, a release note has been provided to provide information to help you design your application so that it will be scriptable when the Yellow Box does provide scriptability. This release note also discusses the document architecture and undo features in some detail.
The ActiveX framework (ActiveX.framework) brings together the first pieces of Yellow Box/ActiveX integration by allowing you to use ActiveX Automation objects in Objective-C. Note that this functionality is currently pre-alpha, meaning the packaging and APIs themselves are subject to change in the next release.
NSDispatchProxy is a concrete subclass of NSProxy that defines proxies for ActiveX Automation objects. When an NSDispatchProxy receives a message, in most cases it forwards the message through DCOM (Distributed Component Object Model) to the real ActiveX Automation object, supplying the return value to the sender of the message if one is forthcoming, and propagating any exception back to the invoker of the method that raised it. See the documentation provided in the framework for more information.
The Application Kit and Foundation now provide more
multithread safety, enough to support AWT's multithreaded drawing
demands and allow developers to do a variety of tasks using
multiple threads. Drawing from multiple threads is supported as
long as each thread uses its own connection to the window server;
this is easily accomplished by using the NSApplication factory
method detachDrawingThread:toTarget:withObject:.
NSStatusBar and NSStatusBarItem are two new classes that provide a way to add items to a system-wide status area. These status-bar classes replace the use of application tiles as well as providing extended functionality. An application can add status-bar items that are strings, images, tool tips, or menus and can invoke an action in a specified target when users click on a status-bar item.
The same API is available on both Macintosh and Windows. On the Macintosh, the items appear on the right hand side of the menu bar. Under Windows, the status items appear as part of the taskbar notification area (usually right side of taskbar). The custom view feature is not supported under Windows.
The Apple menu is now automatically filled with a default list of applications and two special entries that represent the lists of recently used applications and documents. In this release there is no editor with which users can configure the contents of the Apple menu, and both the contents of the list and the storage for the contents is subject to change in the future.
The Application Kit "hack" of changing the first top-level menu to an Apple menu if its title is "Info" still works in this release; however, you should switch your menus to use a real Apple menu.
Any Rhapsody menu that is a part of an application's main menu can be torn off. To tear off a menu start tracking in it as if you were going to choose an item and drag off the bottom of the menu a little distance. The mouse button must be down to tear off a menu. The menus you tear off in an application are remembered and restored as you quit and relaunch the application.
Menus now support keyboard UI: While a menu is tracking you can now use the arrow keys to navigate. Since there is currently no way to start tracking the main menu through the keyboard, this isn't yet very useful for normal menus, but it means that you can use the keyboard to choose items in a popup or pulldown menu. When the focus is on an NSPopUpButton, pressing the space bar pops the menu up. Then you can use the arrow keys to move between items; press the space bar again to choose an item.
Control-click now show the context menu for a view if the view
has one. The Control-click is not seen (as a mouseDown:)
by views that have context menus. Views that do not have context
menus still receive mouseDown: for Control-clicks.
However, using Control as a mouse modifier is discouraged, even
if you don't have context menus. Over time, Yellow Box
applications provided by Apple will migrate away from using
Control-click for anything but context menus.
User key-equivalent overrides: This feature is implemented but the UI for setting them is not in this release.
You can now specify the arrow position for bezel style and borderless pop-up menus.
You can now independently set the horizontal and vertical line and page scroll amounts.
NSSplitView has additional delegate methods to allow you to constrain the resizing and collapsing of the view.
The new convenience method selectTabViewItemWithIdentifier:
allows you to select a tab item by its identifier. As with the
other methods in NSTabView, this method raises an exception if
the identifier is invalid.
In Developer Release 1 on Rhapsody platforms, application
delegates did not receive applicationShouldTerminate:
on power-off or logout events in addition to normal application
termination. This now works properly. If the application delegate
implements this method and returns NO, then the logout or
power-off is cancelled.
Applications that need to distinguish between a termination
associated with the end of a login session and a termination
through a Quit (or Exit) command could do this by registering for
the NSWorkspaceWillPowerOffNotification. This
notification is posted prior to calling applicationShouldTerminate:.
Additional relevant events that occur later in the termination
sequence are the posting of an NSApplicationWillTerminateNotification
and a corresponding message to the application delegate of applicationWillTerminate:,
if it implements the method.
For documents managed by an NSDocumentController, it is not necessary for the application delegate to become involved in the save or cancel process.
Buttons include a new feature makes the border of the button
visible only when the button is enabled and the mouse is over the
button. You can enable or disable this feature by invoking the
method setShowsBorderOnlyWhileMouseInside:; the
current setting of this attribute is returned by the method showsBorderOnlyWhileMouseInside.
These two method are available in both NSButton and NSButtonCell
and this setting is archived and restored. When you are dealing
with matrices, invoke the cell methods directly.
You can override the mouseEntered: and mouseExited:
methods added to NSButtonCell in order to make additional
appearance changes. These methods are invoked when the button
cell is enabled, the showsBorderOnlyWhileMouseInside
flag is set to YES, and the mouse enters or exits the button.
The new method colorizeByMappingGray:toColor:blackMapping:whiteMapping:
supports colorization of images. This method primarily maps
grayscale user interface component images to different color
schemes.
In this release NSBitmapImageRep has some preliminary support for ColorSync profiles in TIFF files. The profile is loaded and used if possible. It is not retained on save. Also, it works only on the PowerPC architecture.
As mentioned in the Developer Release 1 notes, NSBitmapImageRep now supports JPEG, GIF, and PNG reading and writing. This support is not finalized and will probably change for the first Customer Release to include additional formats using QuickTime codecs.
Because different image formats contain additional
information, this information is stored as NSBitmapImageRep
properties. You can set these properties in the image by using
the setProperty:withValue: method and get the
properties with valueForProperty:, or you can add or
override the properties when creating the representation using representationOfImageRepsInArray:usingType:properties:
and representationUsingType:properties: methods. The
properties are stored in an NSDictionary using an NSString for
the key. The following key/value pairs are currently defined:
NSImageCompressionMethod: -- The TIFF
compression method for TIFF files. The enumerated value
is stored in an NSNumber.NSImageCompressionFactor: -- The TIFF and
JPEG compression factor. The float value is stored in an
NSNumber.NSImageDitherTransparency: -- Used for GIF
output only. It is a boolean value stored in an NSNumber.
If true, transparency is dithered to get an alpha channel
effect.NSImageRGBColorTable: -- For GIF input and
output. It consists of a 768 byte NSData object that
contains a packed RGB table with each component being 8
bits.NSImageInterlaced: -- For PNG output; this
value indicates that the output image is to be
interlaced. It is a boolean value stored in an NSNumber.]
Several new factory methods support additional system colors:
keyboardFocusIndicatorColor: -- Color to use
to draw the keyboard focus ring around text fields and
buttons.headerColor: -- Background color for header
cells in Table/OutlineView.headerTextColor: -- Text color for header
cells in Table/OutlineViewRhapsody now supports dynamic updating of color schemes; if
the user changes any of the system colors in the Preferences
application, applications will be updated dynamically. If you
create or cache any custom colors based on system colors, you
might need to listen to the NSSystemColorsDidChangeNotification
and take appropriate action when the color scheme is updated.
As discussed above, NSBitmapImageRep also provides a method to colorize images; this method might come in handy when you are adopting bitmap images in the user interface to new color schemes.
The typedefs NSPointArray, NSSizeArray, NSRectArray,
and NSRangeArray are added to Foundation and the
AppKit to indicate methods and functions that take C-arrays of
NSPoint, NSSize, NSRect, and NSRange.
Similarly, the typedefs NSPointPointer, NSSizePointer,
NSRectPointer, and NSRangePointer are added
to indicate methods and functions that return NSPoints, NSSizes,
NSRects, and NSRanges by reference.
These typedefs do not really change the API, but they do clarify the intentions of the few methods taking pointers to structs, making it possible for the Java bridge to convert them correctly.
The methods availableFontFamilies, availableMembersOfFontFamily:,
and localizedNameForFamily:face: are added to
provide more information about font families.
NSScreenSaverWindowLevel has been added to allow
developers to place windows above everything else, including
menus. NSDockWindowLevel has been deprecated and
should not be used.
The Application Kit now supports a utility look for panels.
This is typically used for small nonmodal panels that float and
hide when the application is deactivated, such as a tools
palette. A utility window is a floating panel by default, but you
can disable this behavior by invoking setFloatingPanel:
with an argument of NO.
You can create utility windows programmatically with the NSUtilityWindowMask
style (which should be specified in conjunction with NSTitledWindowMask),
or in Interface Builder, by enabling the "utility
window" option in the Panel Attribute inspector.
The "Minimize" attribute, which was changed to windowshade windows in Developer Release 1, now either minimizes or windowshades depending on the user preference.
A known problem in this release is the behavior of windows
marked as "Visible at launch" in Interface Builder.
When an application is launched they become visible but they do
not become key even though the application is active. For a
window to become key, makeKeyAndOrderFront: must be
explicitly invoked.
An NSURL class has been added to the Foundation framework. In this release the class only supports file URLs.
Various classes in the Foundation and Application frameworks
have new APIs that take URLs in addition to file names. For
instance, NSData's initWithContentsOfFile: now has a
parallel initWithContentsOfURL:. You can now get
back an array of URLs from the open panel in place of the array
of file names. If your application starts using these new APIs,
it will inherit richer behavior (such as accessing files and
resources over the network) when NSURL class is expanded in
future releases.
NSAttributedString's initWithHTML:documentAttributes:
method has been deprecated in favor of initWithHTML:baseURL:documentAttributes:,
which provides a way to supply the appropriate base URL.
Please note that the prefix HTML is reserved and in use by the (currently private) HTML framework.This framework is dynamically loaded when the Application framework needs to parse HTML files; any conflicts in global names could lead to problems at that time.
Invoking NSImage's imageNamed:method with images
that don't exist can be costly, forcing a search of the
application's main bundle and the Application framework. If you
wish to detect such calls to this method, run your application
with the NSLogMissingNamedImages default set to YES
(as with all defaults, this can also be specified through the
command line).
In Rhapsody and Yellow Box for Windows, the method setKnobThickness:
currently has no effect.
The Foundation framework now contains NSDistributedNotificationCenter, a class for sending notifications between processes on a single machine. In addition to the basic features in NSNotificationCenter, this class provides a way to set a suspension behavior on notifications: You can cause them to be delivered immediately to all applications, or delayed until the applications are not suspended. The Application Kit ensures that applications become suspended when they are deactivated.
Distributed notifications can be expensive if they are sent often and cause the receiving applications to wake up on delivery. For that reason you should use them sparingly and with the suspension behavior generally set to NSNotificationSuspensionBehaviorCoalesce.
There are significant changes in the NSBezierPath APIs, which are not yet documented. Please refer to the header file for the new API.
Compatibility was not maintained between the old and new APIs, so earlier code that used NSBezierPath should be recompiled.
This release introduces some additional input method API. At
the core of interaction, insertText: and setMarkedText:selectedRange:
can receive an instance of NSAttributedString as their arguments
where they were restricted to NSString in the previous releases.
Input servers are expected to query valid attributes with the validAttributesForMarkedText
method. Currently the following attributes are supported by
NSTextView for marked text: Foreground color
(NSForegroundColorAttributeName), background color
(NSBackgroundColorAttributeName), and underline
(NSUnderlineAttributeName).
This release provides more sophisticated programmatic interaction between the user and the input methods, including allowing an input method to track mouse events on text.
When Developer Release 2 ships, Apple's Developer Support web site will make available source code for a sample input method that uses the new APIs to implement a hex input method (allowing you to type a hex number to specify any Unicode character).
By invoking setAutosaveTableColumns: you can get
the column configuration (such as ordering and sizes) of a table
or outline view to be saved, per user, under a key specified via setAutosaveName:.
This works much like the frame saving feature in NSWindow.
Outline view also provides an additional method, setAutosaveExpandedItems:,
to let applications save the expansion state of the viewed data.
To enable this, you will also have to respond to the new
data-source methods that allow the outline view to archive the
items.
Additional delegate methods and notifications in NSOutlineView allow instances to communicate expansion and collapsing of items.
The printing method knowsPagesFirst:last: has
been deprecated in favor of knowsPageRange:, which
is easier to map to Java. The old method will keep on working but
will no longer be documented.
Invoke setAllowsUndo:with an argument of YES to
enable undo in the text system.
If you write your own connection inspector for IB, you may wish to use the NSNibControlConnector, NSNibOutletConnector, and the NSNibConnector classes. NSNibControlConnector provides a target/action connection between objects in a nib file. NSNibOutletConnector provides an outlet connection between objects in a nib file. NSNibConnector is the common base class; you may wish to subclass it for your own custom connectors between objects.
DataLinks, which were made obsolete between NextStep and OPENSTEP releases, have been removed from the framework.
NSComboBoxCell now provides automatic completion of typing.
The way keyboard UI is started on Rhapsody has been modified. In windows without editable textfields, hitting Tab will enter you into keyboard UI mode; until that time, keyboard focus will not be on any UI object. In windows with editable textfields, if an initial first responder has not been specified, the textfield will have the focus when the window is brought up. On Windows the situation is as it was; that is, it works like Windows does.
On Rhapsody, Command-up-arrow and Command-down-arrow used to change the ordering of windows (without making them key). This is no longer the case.
The Escape key (Esc) now no longer does escape completion by default; instead, it cancels the current action (usually dismissing panels). To change Escape back to completion, create or edit the DefaultKeyBinding.dict file in ~/Library/KeyBindings so that it contains this line:
{
"\033" = "complete";
}
Consider NSCStringText and all related API (everything in obsoleteNSCStringText.h) to be deprecated. Although this code will keep working for awhile, it is highly recommended that you switch over to the new text system, which provides much more functionality in a much cleaner way. If there are any reasons that prevent you from moving to the new text system, please let us know through Developer Support.
In DR1, the Application Kit includes these new classes, features, and changes since OpenStep 4.2:
A class for objects that represent PICT images. For the Developer Release, only bitmap PICTs work.
A class for objects that implement a determinate or indeterminate progress indicator. The indeterminate progress indicator can be animated in a separate thread, allowing its use even in computation code that doesn't use the run loop.
Classes for displaying multiple views using tabs.
A subclass of NSTableView that implements an outline representation of hierarchical data. Like NSTableView and NSBrowser objects, NSOutlineView objects use a data source (separate from the delegate) to display the data lazily.
New factory methods create objects that represent additional user interface colors.
As does the Font panel, the Color panel now has a Set button.
When clicked, it sends a changeColor: message down
the responder chain. See the NSColorPanel documentation for
details.
The systemFontOfSize: and boldSystemFontOfSize:
methods have been deprecated in favor of the other factory
methods returning user-chosen fonts. The function NSConvertGlyphsToPackedGlyphs()
was added to allow you to convert an array of NSGlyphs to
"packed" glyphs, suitable for passing to PostScript.
NSImage and NSBitmapImageRep can now read GIF, JPEG, and PNG images directly (that is, without the aid of filter services). JPEG and PNG writing is also supported; GIF writing is planned for a future release. Some APIs were added to NSBitmapImageRep to provide support for features found in these image file types.
These two classes help provide a more complete abstraction in the Application Kit framework layer for graphics operations. NSBezierPath enables standard operations with lines, user-defined paths, and arrays of glyphs, such as stroking, filling, and clipping. It also provides simple bounds computation and hit detection methods. NSAffineTransform provides an abstraction for the graphics transformation matrix.
The abstract superclass for NSDPSContext, this class provides methods to save and restore the graphics state and to change the current graphics context.
NSGraphics has three class methods that do not work correctly in DR2 (calling them has no effect):
fillRectList(NSRect[]) fillRectListWithColors(NSRect[], NSColor[]) clipRectList(NSRect[])
Instead of these methods, use the corresponding "inRange" methods:
fillRectList(rects) ==> fillRectListInRange(rects, new NSRange(0, rects.length)) fillRectListWithColors(rects, color) ==> fillRectListWithColorsInRange(rects, colors, new NSRange(0, rects.length)) clipRectList(rects) ==> clipRectListInRange(rects, new NSRange(0, rects.length))
The look and feel of the split view has changed significantly.
There's no dimple, the split bar is thinner, and you get a resize
image when the cursor is over it. You should use the method dividerThickness
to determine the correct thickness of the bar.
The new method visibleFrame supplies the usable
region (without menu or task bar regions) of a given screen.
Menus and pop-up buttons have changed significantly since OpenStep 4.2. In 4.2, NSMenu and NSMenuItem claimed they were NSObject subclasses, but they were actually subclasses of NSPanel and NSButtonCell. Although the compiler would warn about panel or cell messages being sent to these objects, they would perform as required at run time. In the new implementation, NSMenu and NSMenuItem are true subclasses of NSObject. If your code is sending messages to these objects&emdashwhich assume inheritance from NSPanel and NSButtonCell&emdashit will no longer work.
NSMenu and NSMenuItem include new APIs and functionality.
NSMenuItems may now have titles, key equivalents, images, and
state images. NSMenus have a platform-specific menu
representation that is in charge of presenting the menu to the
user and allowing the user to interact with it. On Mach, the menu
representation is an NSMenuView. NSMenuView allows much leeway in
the way a menu works and looks. An NSMenuView uses
NSMenuItemCells to draw its items. On Windows the menu
representation class is currently private (NSMenu's menuRepresentation
method will return nil).
The NSMenuItem protocol has been deprecated in favor of the NSMenuItem class. Use the class instead of the protocol, which will be dropped from the Application Kit in a future release. There is now a public NSPopUpButtonCell class. See the Application Kit reference documentation for details of the new APIs.
Some planned features are not yet implemented, such as tear offs and key-equivalent overrides. You should not have to do anything special to prepare your application for these coming features. Context menus are supported in the Developer Release, but only for systems with two-button mice. Support will be added in a later release support for Control-click context menus. Your code should not have to change, but you should be aware that using the control key for your own special mouse features is probably not a good idea since that modifier key will soon have another meaning.
Sliders now support tick marks that identify specific values on the slider continuum. Clicking these tick marks returns the represented value.
NSTextView objects can now read HTML files. A delegate method is provided for following HTML links.
Delegate methods for clicking on cells have been augmented
with an argument to specify the character index of the click; for
instance, textView:clickedOnCell:inRect:atIndex:
instead of textView:clickedOnCell:inRect:. The old
delegate methods will continue to work, but you should plan to
replace them with the new ones.
The text system now treats control-L ("form feed") as a container break character. A control-L forces the layout to continue onto the next container. However, the text system also tries to recognize the infinitely-growing container case (which is the usual situation in applications such as TextEdit and Project Builder), and ignores the control-L in these cases.
On non-Windows platforms, an application can now choose to
quit when the last window is closed. If the application delegate
responds to applicationShouldTerminateAfterLastWindowClosed:
by returning YES, the application is sent a terminate:
message when the last window is closed.
On Windows systems there has been no change. If the last
window of an application is closed, and if the window contained
the application menu, the application is sent the terminate:
message by default. The delegate can prevent this by
responding NO to applicationShouldTerminateAfterLastWindowClosed:.
Instead of miniaturizing, windows now use a feature called WindowShading: when the user clicks the appropriate window control, the window's content view disappears and just the title bar remains (this can be toggled back to the original state). Windows also have a zoom button, which switches a window between a standard (size-to-fit) size and a user size. The standard size can be set by calls to the delegate.
A document icon in the title bar gives access to the document represented by the window; users can drag and drop the document directly (this replaces the "Alternate-drag from the miniaturize button" model of OPENSTEP 4.2).
Two new methods in NSView, didAddSubview: and willRemoveSubview:,
provide ways to detect subview list changes.
These classes now support mixed-state cells. You can enable
this feature with the setAllowsMixedState: method,
which allows the cell to be in NSMixedState mode in addition to
NSOnState and NSOffState. In addition, various bezel styles have
been added to support the range of button styles available on the
Mac:
(Although the header file refers to NSNeXTBezelStyle, NSPushButtonBezelStyle, NSSmallIconButtonBezelStyle, NSMediumIconButtonBezelStyle, and NSLargeIconButtonBezelStyle, these styles are obsolete and should not be used.)
The Rhapsody Developer release contains an alpha version of the Java APIs for the Yellow Box. By using these APIs you can access virtually all classes and protocols of the Application Kit and Foundation frameworks. However, since this is an alpha version, these APIs are not yet complete and will most likely change before the next release.
The constant NSMacintoshInterfaceStyle has been added to represent the Rhapsody user interface. NSNextStepInterfaceStyle has been removed.
When creating resources, use the suffixes
"-macintosh" and "-windows" to indicate any
resources that are specific to a particular interface style. The
base resource must be available (for instance, foo.nib);
all the other interface-style specific ones (such as foo-windows.nib)
are optional. This is a feature of NSBundle, and will work with
any resource, not just nibs.
This section is provided as a quick guide to developers converting applications from NextStep 3.x to the Yellow Box. OpenStep 4.2 was the last release shipped by NeXT before the Apple purchase.
OpenStep: Release 4.0 brings numerous API changes to
the AppKit relative to Release 3.3. Tools and scripts provided to
convert a 3.x application to OpenStep are included with the 4.x
releases, in /NextLibrary/Documentation/NextDev/Conversion/ConversionGuide....
New Text System: Release 4.0 includes a new text system composed of several different classes: NSTextView (front-end UI), NSTextStorage and NSAttributedString (back-end text storage), NSLayoutManager (management of text layout process and info), and NSTextContainer (description of text flow areas). These classes provide an open, powerful interface and allow text editing in multiple languages, using the Unicode standard.
FileWrapper: NSFileWrapper, a new class, provides support for the concept of a document wrapper (like a .rtfd or ....nib). It handles reading and writing file packages in the file system as well as serializing them for use with the Pasteboard.
TableView: DBKit's table view class has been completely rewritten and moved into the AppKit as NSTableView. All four classes making up the new TableView are public and fully subclassable.
Keyboard UI: Keyboard access is now provided to most of the controls in the AppKit.
Formatting and Validation: Cells may now be assigned arbitrary object values, which are converted into presentation strings by associated formatter objects. This allows the developer to directly set an NSDate, for instance, as the value of a cell. The cell's associated date formatter will present a localized string representation of the date to the user. The formatter objects, along with control delegates, can also perform validation on user-entered data, thereby restricting entries to valid ranges or quantities.
Rich Text in Cells: NSCell and subclasses can now display and edit rich text. The rich text is specified via instances of NSAttributedString. The new formatting/validation API also includes support for attributed strings.
RulerView: NSRulerView is designed as a general-purpose ruler that can be associated with any scroll view and used by any view that's in the scroll view. It supports both horizontal and vertical rulers, allows arbitrary markers along the rule, and can accept an accessory view.
System Colors: New API has been added to access system-defined colors, such as the color of buttons, controls, text and text selection colors. On Windows, where the user can change the system colors at any point, these colors will change at runtime to match the user's selection.
Image: NSImage now understands the bmp, ico, and cur image formats. ico and cur files with multiple images will be loaded as images with multiple representations. Typically these representations will have different sizes (unlike multiple-representation tiffs, which have different depths); by default, NSImage will choose the largest image when compositing.
NSApplicationMain: The AppKit now provides a function NSApplicationMain() to take care of the initialization and startup of your application. This function is declared in NSApplication.h.
ObjectLinks: ObjectLinks have been removed from the OpenStep specification, and in general the feature is not supported in OpenStep for Mach or Windows.
Help System: The AppKit's Help API has changed significantly. NSHelpPanel has been obsoleted in favor of a new class, NSHelpManager, which provides a more platform-independent approach to presenting both context-sensitive and comprehensive help.
ComboBox: NSComboBox class has been added to the Application Kit. It offers functionality that is similar to the Combo Box control used in the Microsoft Windows user interface.
Splash Screen: OpenStep for Windows now provides
support for a "splash" screen in applications; this is
basically a panel that comes up with a static image as the
application is launched. To use this feature, simply provide an
8-bit uncompressed bitmap (.bmp) image named Splash.bmp
as a resource in your application. You can make it localizable if
you wish (thus the image can be either in appname.app/Resources/
or appname.app/Resources/language.lproj/)
NSApplication: By default, on OpenStep for Windows,
only a single copy of an application will be launched. If you
wish to run multiple copies, you should use specify a value of NO
to the -NSUseRunningCopy command line option. In
addition, all command-line options that are not defaults options
(meaning a pair of arguments where the first one starts with a
"-") are now treated as file names to be opened, as if
they were prefixed with -NSOpen. As a result of
these two changes, you can now associate documents with OpenStep
applications on Windows simply by specifying the location of the
application. The default command line provided by the Explorer
suffices to open documents and also to connect to a running copy
of the application, if there is one.
Window edited status: In OpenStep for Windows, an asterisk in a window's title bar indicates that the associated document has been edited.
Tracking rectangles: Tracking rectangles are now implemented on Windows.
NSWindow frame vs content rect: On Windows, the frameRect and contentRect of an NSWindow are currently the same size. Thus the frameRect of an NSWindow does not include the title bar, menu bar, resize border, and so on (but does on Mach). Also, the contentView while a window is miniaturized is an NSImageView, not the original contentView. The contentView is restored when the window is deminiaturized.
NSTextView: On Windows, to allow entering a character
without an appropriate keyboard, you can now use the Alternate
key in conjunction with the digit keys from the keypad. While
holding down the Alternate key, type the index of the desired
character in the encoding of the current font (in most cases this
will be the NEXTSTEP encoding). The appropriate character will be
inserted into the text when the Alternate key is released.
SplitView: NSSplitView now supports horizontal as well vertical splits.
ToolTips: It's now possible to add "tooltips" (short help messages that pop up as the user holds the mouse cursor over an item) to views. You can do this programmatically or by using Interface Builder's Help panel.
Text Hyphenation and Justification: The text object now supports full justification and hyphenation, with a fairly basic API.
ComboBox cell: There is now a public NSComboBoxCell class. This feature allows you to use combo boxes in table views, among other places.
Hiding applications on Windows: Support for the "hide application" command has been added to OpenStep for Windows. The default menu item for this is Minimize All in the Windows menu (with Control-h as the key equivalent). The Application Kit adds this item automatically if it is not in the menu.
CMYK archiving problem: A bug in decodeNXColor
that caused CMYK colors from 3.x archives to be read
incorrectly in 4.0 and 4.1 has been fixed. (The colors were way
off base; instead of C, M, Y, K, the values 1-C, 1-M, 1-Y, and
1-K were used.)